<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
   <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   <title>Levels Avisynth Filter</title>
   <link rel="stylesheet" type="text/css" href="../../avisynth.css">
</head>
<body >
<h2>
<a NAME="Levels"></a>Levels
</h2>
<p><code>Levels </code>(<var>clip, int input_low, float gamma, int input_high,
int output_low, int output_high, bool &quot;coring&quot;, bool
&quot;dither&quot;</var>)
<p>The <code>Levels</code> filter adjusts brightness, contrast, and gamma (which
must be &gt; 0).
The <var>input_low</var> and <var>input_high</var> parameters determine what input
pixel values are treated as pure black and pure white, the <var>output_low</var>
and <var>output_high</var> parameters determine the output values corresponding
to pure black and white and the <var>gamma</var> parameter controls the degree
of nonlinearity in the conversion. To be precise, the conversion function
is:<br>
<blockquote>output = [(input - input_low) / (input_high -
input_low)]<sup>1/gamma</sup>
(output_high - output_low) + output_low</blockquote>
This is one of those filters for which it would really be nice to have
a GUI. Since I can't offer a GUI (at least not in AviSynth's current form),
I decided I could at least make this filter compatible with VirtualDub's
when the clip is RGB. In that case you should be able to take the numbers
from VirtualDub's Levels dialog and pass them as parameters to the <code>Levels</code>
filter and get the same results. However, the input and output parameters can be larger than 255.
<p>When processing data in YUV mode, <code>Levels</code> only gamma-corrects
the luma information, not the chroma. Gamma correction is really an RGB
concept, and I don't know how to do it properly in YUV. However, if <var>gamma</var>
= 1.0, the filter should have the same effect in RGB and YUV modes. For
adjusting brightness or contrast it is better to use <a href="tweak.htm">Tweak</a>
or <a href="coloryuv.htm">ColorYUV</a>, because <code>Levels</code>  also
changes the chroma of the clip.
<p>In <em>v2.53</em> an optional <var>coring</var> = <var>true/false</var>  (true by default, which reflects the behaviour in older versions) is added.
<p>
 <var>coring</var>  = true/false (true by default): When set to true: input luma is clamped to [16,235] (and the
chroma to [16,240]), this result is *scaled* from [16,235] to [0,255], the
conversion takes place according to the formula above, and output is *scaled*
back from [0,255] to [16,235]. When set to false, the conversion takes place
according to the formula above.</p>
<p><i><var>dither</var></i> = true/false (false by default): When set to true, <a href="http://avisynth.org/mediawiki/Ordered_dithering" title="Ordered dithering">ordered
dithering</a> is applied when doing the adjustment.</p>
<pre># does nothing on a [16,235] clip, but it clamps (or rounds) a [0,255] clip to [16,235]:
Levels(0, 1, 255, 0, 255)

# the input is scaled from [16,235] to [0,255], the conversion [0,255]-&gt;[16,235] takes place (accordingly to the formula),
# and the output is scaled back from [0,255] to [16,235]: (for example: the luma values in [0,16] are all converted to 30)
Levels(0, 1, 255, 16, 235)

# gamma-correct image for display in a brighter environment:
# example: luma of 16 stays 16, 59 is converted to 79, etc.
Levels(0, 1.3, 255, 0, 255)

# invert the image (make a photo-negative):
# example: luma of 16 is converted to 235
Levels(0, 1, 255, 255, 0)

# does nothing on a [0,255] clip; does nothing on a [16,235]:
Levels(0, 1, 255, 0, 255, coring=false)

# scales a [0,255] clip to [16,235]:
Levels(0, 1, 255, 16, 235, coring=false)  # note both luma and chroma components are scaled by the same
                                          # amount, so it's not exactly the same as ColorYUV(levels=&quot;PC-&gt;TV&quot;)
# scales a [16,235] clip to [0,255]:
Levels(16, 1, 235, 0, 255, coring=false)  # note both luma and chroma components are scaled by the same
                                          # amount, so it's not exactly the same as ColorYUV(levels=&quot;TV-&gt;PC&quot;)
# makes a clip 100% black
Levels(0, 1.0, 255, 0, 0)</pre>

<p><b>Changes</b></p>
<table border="1" cellpadding="4" cellspacing="1">
  <tbody>
    <tr>
      <td>v2.53</td>
      <td>added coring</td>
    </tr>
    <tr>
      <td>v2.60</td>
      <td>added dither</td>
    </tr>
  </tbody>
</table>

<p><kbd>$Date: 2012/04/09 08:19:32 $</kbd></p>
<form><input TYPE="Button" VALUE="Back"
onClick="history.go(-1)"></form>
</body>
</html>
